package vip.liux.contracts.security.core.extensions;

import java.util.Optional;

/**
 * 提供用于管理用户账户的存储抽象。
 *
 * @param <TUser> 封装用户的类型
 */
public interface IUserStore<TUser> extends AutoCloseable {

    /**
     * 获取指定用户的唯一标识符。
     *
     * @param user 需要获取标识符的用户
     * @return 指定用户的唯一标识符
     */
    String getUserId(TUser user);

    /**
     * 获取指定用户的用户名。
     *
     * @param user 需要获取用户名的用户
     * @return 指定用户的用户名
     */
    String getUserName(TUser user);

    /**
     * 为指定用户设置用户名。
     *
     * @param user     需要设置用户名的用户
     * @param userName 要设置的用户名
     */
    void setUserName(TUser user, String userName);

    /**
     * 获取指定用户的标准化用户名。
     * 标准化用户名通常用于不区分大小写的用户查找。
     *
     * @param user 需要获取标准化用户名的用户
     * @return 指定用户的标准化用户名
     */
    String getNormalizedUserName(TUser user);

    /**
     * 为指定用户设置标准化用户名。
     *
     * @param user           需要设置标准化用户名的用户
     * @param normalizedName 要设置的标准化用户名
     */
    void setNormalizedUserName(TUser user, String normalizedName);

    /**
     * 在用户存储中创建指定的用户。
     *
     * @param user 要创建的用户
     * @return 创建操作的结果
     */
    IdentityResult create(TUser user);

    /**
     * 在用户存储中更新指定的用户。
     *
     * @param user 要更新的用户
     * @return 更新操作的结果
     */
    IdentityResult update(TUser user);

    /**
     * 从用户存储中删除指定的用户。
     *
     * @param user 要删除的用户
     * @return 删除操作的结果
     */
    IdentityResult deleteUser(TUser user);

    /**
     * 根据用户ID查找并返回用户（如果存在）。
     *
     * @param userId 要搜索的用户ID
     * @return 包含匹配指定用户ID的用户的Optional对象，如果不存在则为空
     */
    Optional<TUser> findById(String userId);

    /**
     * 根据标准化用户名查找并返回用户（如果存在）。
     *
     * @param normalizedUserName 要搜索的标准化用户名
     * @return 包含匹配指定标准化用户名的用户的Optional对象，如果不存在则为空
     */
    Optional<TUser> findByName(String normalizedUserName);

    /**
     * 释放存储使用的所有资源。
     * 实现应确保在此方法被调用后不能再使用存储。
     *
     * @throws Exception 如果关闭过程中发生错误
     */
    @Override
    void close() throws Exception;
}